home *** CD-ROM | disk | FTP | other *** search
/ Floppyshop 2 / Floppyshop - 2.zip / Floppyshop - 2.iso / diskmags / 0022-3.564 / dmg-0134 / miscell / atar_bin.txt next >
Text File  |  1997-04-16  |  16KB  |  244 lines
  1. Atari Binary Transfer Format ("ABTF") Standard Proposal
  2.  
  3. Russ Wetmore [76703,2010] 30 Nov 1985
  4.  
  5. -------------------------------------------------------------------------
  6. Modified 15 Jun 85: Added suggested file naming conventions & fixed errors.
  7.      30 Nov 85: Clarified ST-specific parameters
  8. -------------------------------------------------------------------------
  9.  
  10.   SOME BACKGROUND INFORMATION: THIS PROPOSAL IS BASED ON A SIMILAR ONE MADE BY
  11. DENNIS BROTHERS, CALLED "MACBINARY." (I.E. I lifted whole sections from it.
  12. Most, if not all, of the credit should lie with Dennis, and Mike Boich and
  13. Martin Haeberli, whose MacTerminal program provided the basis for this standard.
  14. Dennis' proposal is available in the Macintosh Users SIG (G PCS-23) if you want
  15. to compare them.) MACBINARY IS QUICKLY BECOMING AN INDUSTRY-WIDE STANDARD, AS
  16. OPPOSED TO MERELY A SYSTEM-SPECIFIC ONE. IN MANY WAYS THIS PROPOSAL IS SIMILAR
  17. ENOUGH TO MACBINARY FOR POSSIBLE CROSS-COMPATIBILITY BETWEEN ABTF AND FUTURE
  18. COMPUTERS' FILE TRANSFER NEEDS.
  19.  
  20. -------------------------------------------------------------------------
  21.  
  22.   The following notes are a proposal for a standard format for binary transfer
  23. of arbitrary Atari files via a telecommunication link. It is intended for use
  24. both between Ataris running (possibly different) terminal programs which adhere
  25. to the standard, and for use in uploading arbitrary Atari files to remote
  26. systems (where it is presumed that they will be stored as an exact image of the
  27. data transmitted). A proposal is also made for standard processing to be
  28. performed on text files transferred via a protocol, to maximize the likelihood
  29. that text files transmitted to a remote system will be usable by that system,
  30. and that text files received from a remote system will be usable by an Atari
  31. user.   It is recommended that the format and procedures described here be
  32. referred to as "ABTF", and that any terminal program implementing this format
  33. and procedures be called "ABTF-Compatible". It is also STRONGLY recommended that
  34. files transferred under this standard utilize the extension ".ABT" on hosts to
  35. signify usage of the standard.  Since the actual filename is stored in the
  36. transmitted header, the downloader can resolve the proper filename without
  37. having to intervene in the process.   The binary format described is independent
  38. of the communication protocol used to accomplish the transfer, and assumes only
  39. that an 8-bit transparent transfer can be accomplished. THIS IS AN IMPORTANT
  40. POINT! THIS FORMAT IS NOT A PROTOCOL, BUT MERELY A METHOD OF FORMATTING A FILE
  41. SO THAT IT CAN BE LOGICALLY  RECONSTRUCTED WHEN DOWNLOADED!  Such protocols as
  42. Christensen (usually referred to as XMODEM or MODEM7), Kermit, and CompuServe A
  43. or B meet this requirement. Because of the proposed standard's XMODEM heritage,
  44. there is a requirement that the transmitted data be padded (with nulls) to a
  45. 128-byte boundary at certain points, but this in no way implies that a
  46. block-oriented protocol must be used. The basic format proposed is similar to
  47. that used by Apple's MacTerminal program, written by Mike Boich and Martin
  48. Haeberli.   In brief, the binary format consists of a 128-byte header containing
  49. all the information necessary to reproduce the file's directory entry on the
  50. receiving Atari;  followed by the file's data (padded, if necessary, to a
  51. multiple of 128 bytes). The length of the data is contained in the header. The
  52. format of the 128-byte header is as follows (offsets and lengths are given in
  53. decimal):
  54.    Offset  Length   Contents   ------  ------
  55.    -----------------------------------------------
  56.    000    1    Zero. This is a "version" byte.
  57.    001    1    Length of filename.
  58.    002    63    Filename (only "length" bytes are significant).
  59.              (Note: bytes beyond the physical limit of
  60.              the filename size for a particular computer's OS
  61.              are NOT guaranteed to be any particular value.)
  62.              For compatibility and integrity purposes, only the
  63.              filename itself (sans device and subdirectory
  64.              specifiers) should be included. It is up to the
  65.              receiving terminal program to assign the desired
  66.              device path.
  67.    065    8    Non-guaranteed or system-specific information.
  68.    073    1    File attributes. The only attribute supported on
  69.              8-bit versions would be whether or not a file is
  70.              locked - bit 0 is 1 if locked, 0 if not. On ST
  71.              systems, this byte is the one returned by the
  72.              Fattrib() GEMDOS call:
  73.                bit 7 - (not used)
  74.                bit 6 - (not used)
  75.                bit 5 - Closed
  76.                bit 4 - Subdirectory label
  77.                bit 3 - Volume label
  78.                bit 2 - System file
  79.                bit 1 - Hidden
  80.                bit 0 - Read only
  81.    074    1    GUARANTEED Zero.
  82.    075    7    Non-guaranteed or system specific disk information.
  83.    082    1    GUARANTEED Zero.
  84.    083    4    Data length (bytes).
  85.    087    4    Non-guaranteed or system-specific information.
  86.    091    8    File's creation date. (For the ST, and those 8-bit
  87.              DOSes that support a real-time clock, like
  88.              SpartaDOS. Zero filled if not supported.
  89.              Time is represented in the following format:
  90.                091  1 Day    (1 to 31)
  91.                092  1 Month   (1 to 12)
  92.                093  1 Year    (0 to 127: years since 1980)
  93.                094  1 Hours   (0 to 23: 24 hour format)
  94.                095  1 Minutes  (0 to 59)
  95.                096  1 Seconds  (0 to 59)
  96.                097  2 Reserved
  97.              Note that this could easily be altered to support
  98.              TWO dates by utilizing 4 bytes each to represent
  99.              each date, using the ST GEMDOS format for time/date
  100.    099    25    Zero fill (reserved for expansion of standard).
  101.    124    2    CRC of the first 124 bytes of the header block,
  102.              for integrity purposes.
  103.    126    1    Computer type. Proposed to be $01 for Atari
  104.              computers. ($00 currently refers to a Macintosh.)
  105.    127    1    Computer OS ID. Proposed to be $00 for Atari 8-bit
  106.              computers, and $01 for ST's. ($00 currently refers
  107.              to a Macintosh.)
  108.    Note that it is the responsibility of the receiving terminal program to
  109. resolve file name conflicts, generally by somehow modifying the name of received
  110. file if there already exists a file with the original name on the target disk.
  111. It is suggested that Atari-based terminal programs implement two modes of
  112. protocol transfer: text and binary. Text mode is used for unformatted files of
  113. ASCII text (i.e. no control characters except TAB, FF, CR and LF; or "inverse"
  114. characters, meaning characters with the high bit set), and binary mode (using
  115. the binary format proposed here) is used for all other files. Binary mode may
  116. also be used on text files, of course, if it is desired to preserve such things
  117. as the file's creation date and attributes. The intent of text mode is to
  118. provide compatibility with text files on other systems. Towards that end, it is
  119. recommended that a linefeed be inserted after each return character as the text
  120. file is transmitted, and that, in the case of block-oriented protocols, the last
  121. block be explicitly padded with zeros if the text does not end on a block
  122. boundary.  When receiving in text mode, linefeeds and trailing zeros should be
  123. stripped. If a CTRL-Z (Hex 1A) character is received following all other text
  124. (and before any null padding), it should also be stripped (Ctrl-Z is commonly
  125. used as a text terminator on GEMDOS and some other systems). Note that the above
  126. discussion applies only to text files transferred under some protocol, where an
  127. exact image of the transmitted data will be stored in a file on the remote
  128. system.   When receiving a file via a protocol, a terminal program may
  129. distinguish between ABTF-formatted, and non-standard or text modes quickly by
  130. examining bytes 0, 74, and 82 of the first 128 bytes received. If they are each
  131. zero (and at least 128 bytes have been received), then an integrity check should
  132. be made using the CRC value in bytes 124 and 125. This CRC value would be a
  133. standard 16-bit cyclic redundancy checksum (too technical to describe here)
  134. calculated using the first 124 bytes of the header block. If the CRC value is
  135. determined to be correct, then it is very safe (i.e. 99.99..% assured) to assume
  136. that an ABTF-formatted file is being received.   Terminal programs implementing
  137. possible future versions of the proposed standard would, of course, accept an
  138. appropriate set of version numbers in byte 0.  Note also that compatible
  139. extensions of Version 0 of the proposed standard are possible that involve
  140. transmission of additional information following the information described here.
  141. For this reason, a terminal program should be implemented so as to perform the
  142. proper receive procedures for all data sent to it, but to ignore any data that
  143. it does not know what to do with.   Since a text-mode document does not contain
  144. a file name, it is suggested that when text-mode is detected, a file be opened
  145. under a dummy name on the receiving Atari, the text written to that file, and
  146. the file renamed to a name selected by the user after the reception is
  147. completed. This will avoid problems caused by indeterminate delays for name
  148. selection at the beginning of the file transfer.   It is desirable to allow the
  149. user to specify the destination disk drive in advance of the actual start of
  150. transfer for either type of transfer. Two methods are suggested for this:
  151. provide a "Select Destination Drive" menu selection, presumably in the menu
  152. containing the "Receive File" selection; or query the user immediately after the
  153. "Receive File" menu selection is made. Either or both of these methods could be
  154. implemented in a given terminal program - the independent "Select Receive Drive"
  155. method is particularly desirable if an automatic receive facility is
  156. implemented. Note that this proposed standard lends itself VERY well to such a
  157. facility. (See Addendum A for a suggested procedure for implementing batch
  158. transfers.)  A short history of Atari-based terminal programs and why we need
  159. ABTF
  160.  
  161. ---------------------------------------------------------------------
  162.  
  163.    In the beginning (to coin a phrase) there were no terminal programs available
  164. for Atari 8-bit computer owners.  Jim Steinbrecher of M.A.C.E. developed what
  165. has become the basis for most all Atari terminal programs to date: his AMODEM
  166. terminal and AMIS BBS programs.  Without getting into technical details, there
  167. are several conventions of Atari's DOSes that make it fundamentally impossible
  168. to use the XMODEM transfer standard without some modifications. Jim, William
  169. Volk, and others worked out a kludge that persists to this day.  Unfortunately,
  170. the method they worked out has a couple of problems of its own, most notable of
  171. which is incompability between Atari 8-bit terminal programs and foreign
  172. computer systems (like the Atari ST.)   The beauty of this simple extension is
  173. that it makes transferred files transparently  compatible  between any computer
  174. systems, no matter what downloading protocol is being used. For systems such as
  175. CompuServe, Delphi and People Link; which don't support this standard; an image
  176. of an uploaded file is maintained which a terminal program (which DOES support
  177. the standard) can interpret.  Note that since the protocol being used is NOT
  178. important, a file uploaded using XMODEM protocol could be downloaded using
  179. CompuServe A- or B-protocol, or whatever protocol system the user's terminal
  180. program is capable of handling, within the constraints of this proposed
  181. standard. Also, I assume that many Atari sysops, for example, will be
  182. "upgrading" their BBSes to ST model computers, but will want to continue to
  183. support the old 8-bit computers in their download libraries - this proposal
  184. would allow files for any type computer to be stored a host, no matter what the
  185. host supports.   It is assumed that patches to AMODEM and other popular public
  186. domain and commercial terminal programs to support this standard would be made
  187. available in short order. Note that some modem manufacturers (like Hayes) have
  188. indicated that they are modifying their own terminal programs to support
  189. versions of this transfer standard.   Please address comments or questions on
  190. the above proposals to:
  191.  
  192.      Russ Wetmore
  193.      Star Systems Software, Inc.
  194.      80 Chaney Drive
  195.      Casselberry, FL 32707
  196.  
  197.      CompuServe I.D.: 76703,2010
  198.      Delphi I.D.:   RUSSW
  199.      PLINK I.D.:   ATARI*RUSS
  200.  
  201.    (Final note: Atari 8-bit HomeTerm will be supporting this standard (or a
  202. similar one) in its next update, and ST HomeTerm will feature it on release. I
  203. have spoken with other terminal program authors who have expressed tentative
  204. support of this standard in their programs.  Also, during the changeover
  205. process, until more terminal programs supported this standard, a SIMPLE utility
  206. would be required to translate ABTF-formatted programs by non-supported terminal
  207. programs.  I stress the word SIMPLE. The actual translation process is minimal,
  208. and requires nothing more than fetching the length of the data after the header,
  209. skipping over the header, and reading/writing the given length to the target
  210. file.)
  211.  
  212. Addendum A ---------- First proposed extension to ABTF -----------------------
  213.  
  214.   It is proposed that byte 99 of the header block be considered a "block
  215. transfer" flag. A value of 0 would mean that only this one file is being sent. A
  216. non-zero value in byte 99 would mean that another file follows this one. Each
  217. file to be sent would have its own header block. This process would continue ad
  218. infinitum until a header is received with a zero in byte 99 (meaning no more
  219. files follow after completing the download of this one.)   Note that folder/file
  220. relationships could be maintained - a subdirectory can be considered a file of
  221. zero length with the subdirectory file attribute bit set.  Another possible
  222. extension here would include a provision for "selecting" a subdirectory,
  223. previously created, in order to properly ascertain parent/child subdirectory
  224. relationships.  Possible extensions to ABTF contingent on technical details
  225.  
  226. -----------------------------------------------------------
  227.  
  228.    On the ST, document type classification is desired in order for an
  229. application to automatically open when an associated document is "opened." This
  230. would mean directly manipulating the DESKTOP.INF file on the target disk, whose
  231. location cannot be determined automatically. Also, unless an application is
  232. specifically extended with .TOS or .TTP extenders, the DESKTOP.INF file might
  233. also be desired to be manipulated to simulate the "Install Application" function
  234. of the Desktop program.   GEMDOS has a "load and execute process" function. This
  235. function allows programs to call other programs, with control returning to the
  236. parent process on termination of the child process. A provision could be made to
  237. directly execute a just-downloaded file to perform specific tasks, such as
  238. display graphics pictures (whose data would immediately follow), specially
  239. handle specific BBS features (such as "foreign" downloading protocols not
  240. understood by the terminal program), etc.   A possible, but highly recommended
  241. against, extension would involve alerting the host terminal program to
  242. comprehend the "8-bit Atari XMODEM kludge" for special ST<->Atari 8-bit computer
  243. situations.
  244.